如何管理專案版本？

建置成功只能表示某次執行產生了結果。如果無法回答結果來自哪一筆原始碼、使用哪些設定、通過哪些檢查，以及部署至何處，就難以比較問題發生前後的差異，也無法可靠重現可用版本。

專案版本管理要為原始碼、發布內容、建置成品（Artifact）與部署結果建立穩定身分。各種版本不必使用相同編號，但必須能互相追溯，並且在內容變更時產生新的識別。

先區分不同版本的用途

「版本」可能指向不同內容。先分清責任，才能決定命名方式與保存位置。

部署名稱或檔名可以方便閱讀，不能成為唯一識別。例如，同一個 latest 標籤可能在不同時間指向不同內容。追查時應該使用不隨內容重新指定的提交識別、成品摘要或等效機制。

確認哪些內容要一起版本化

原始碼只是可重現系統的一部分。會影響建置、測試與執行結果的內容，也應該納入相同變更流程：

• 保存建置腳本、套件資訊清單、鎖定檔案與工具設定。
• 保存資料結構異動、遷移程式與相容期間需要的轉換規則。
• 保存非敏感的設定結構、設定範本與必要欄位說明。
• 保存測試程式、測試資料產生方式與可自動判斷的驗收門檻。
• 保存部署定義、健康檢查與部署後驗證指令。
• 保存會隨程式變更的介面契約、結構描述與操作文件。

密碼、權杖、私鑰與其他敏感內容不得進入版本庫。正式值應該由受控的設定或秘密管理機制提供，版本庫只記錄欄位名稱、取得方式與驗證規則。

讓提交紀錄表達修改目的

每筆提交應該涵蓋一個可以說明及驗證的修改目的。實作、相關測試與必要文件可以放在同一筆提交，因為它們共同完成一項變更。互不相關的格式調整、套件更新與功能修改則適合拆開，縮小審查及問題定位範圍。

提交訊息至少要回答「改了甚麼」與「為甚麼要改」。如果需要讓工具解析類型與影響範圍，可以採用約定式提交（Conventional Commits）或自訂的等效格式。採用後還要定義允許的類型、範圍名稱、重大變更表示方式與檢查時機，不能只要求訊息帶有固定前綴。

分支策略負責控制變更如何合併，版本規則負責指出哪些內容形成一次發布。無論採用短期功能分支或主幹式開發，準備發布的提交都要固定，並且能對應到通過檢查的結果。

使用標籤固定發布點

Git 標籤可以讓發布名稱指向明確的提交。Git 的標籤文件區分輕量標籤（Lightweight Tag）與附註標籤（Annotated Tag），附註標籤會保存建立者、時間與訊息，也可以按照需要簽署，較適合正式發布。

發布標籤應該遵守下列原則：

• 每個發布標籤只指向一個已通過發布條件的提交。
• 已公開使用的標籤不得改指向其他提交，內容修正要建立新版本。
• 標籤名稱、發布版本與變更紀錄使用相同命名規則。
• 如果需要確認發布來源，應該驗證標籤、提交或成品的簽署結果。

標籤只固定原始碼位置，不代表建置成品已經產生或通過測試。後續仍要保存標籤、提交、管線執行與成品識別之間的關係。

定義發布版本規則

發布版本可以採用已定義的語意化版本規則，也可以按照日期、核准批次或其他適合的方式識別。採用哪一種格式，取決於需要表達的相容性與發布流程，同一專案應該保持一致。

版本規則要明確記錄增加版本的條件、相容性承諾與停止支援規則。已公開的版本內容如果需要修正，應該建立新的版本識別，並且更新變更紀錄、成品與部署追溯關係。

分開維護變更紀錄與發布說明

變更紀錄與發布說明都描述版本差異，但讀者與細節不同。

提交紀錄不能直接取代這兩份內容。單筆提交著重修改過程，發布文件則要整理使用對象真正需要知道的結果。自動產生初稿時，仍要檢查分類、移除內部雜訊，並補上遷移與相容注意事項。

讓建置成品具有不可變更的身分

同一個提交在不同時間建置，仍可能因工具、相依項目或輸入設定不同而產生不同結果。每份建置成品應該保存下列資訊：

• 記錄來源提交、發布標籤與建置流程版本。
• 記錄建置工具、鎖定的相依結果與必要的輸入版本。
• 產生成品摘要或等效內容識別，供後續下載與部署時重新驗證。
• 連結測試結果、套件組成資訊及建置期間產生的檢查報告。
• 成品建立後不得直接覆寫，任何內容變更都要產生新識別。

如果部署單位是容器映像，可以使用映像摘要固定內容。開放容器倡議（Open Container Initiative, OCI）的內容描述元（Descriptor）規格將摘要用作內容識別，映像註釋（Annotation）規格則提供來源位置、版本與修訂識別等欄位。標籤可以保留容易閱讀的版本名稱，實際部署紀錄仍應該保存摘要。

其他形式的成品也要採用等效原則。例如，壓縮檔、安裝程式或可執行檔可以保存版本資訊與內容摘要，讓下載、測試及部署步驟確認使用同一份檔案。

管理同時存在的相容版本

正式切換期間可能同時存在不同版本的目標程式、遷移工具、保存結構與互動契約。版本管理要記錄哪些組合受到支援，不能只為每個項目各自加上編號。

相容性紀錄至少要說明：

• 指定程式版本可讀取及寫入哪些保存結構版本。
• 指定遷移工具支援哪些來源、目標與重複執行條件。
• 如果系統具有跨程序互動，記錄可同時運作的介面或訊息版本。
• 設定結構變更時，記錄必要欄位、預設行為與淘汰期限。
• 說明哪些更新可以還原，哪些異動只能向前修正。

保留前一份程式成品不代表一定能安全還原。資料或保存結構如果已經發生不相容變更，先前程式可能無法讀取目前內容。發布前要驗證實際相容組合，並將復原限制寫入部署決定。

建立完整的版本追溯鏈

版本紀錄要能從任一端往回查詢。發現執行中的問題時，應該能從部署紀錄找到成品，再找到來源與驗證結果。準備重新部署某個提交時，也應該能找到已經建置及驗證的成品。

欄位名稱可以按照現有工具調整，追溯方向不能中斷。建置紀錄或成品如果會到期刪除，也要確保保留期限涵蓋問題追查、復原與必要的稽核期間。

完成版本管理的檢查

• 原始碼、建置設定、測試、遷移程式與部署定義是否使用一致的變更流程？
• 每筆提交是否具有可以說明及驗證的修改目的？
• 發布版本是否具有明確增加條件與相容性承諾？
• 已公開的發布標籤與成品是否保持不可變更？
• 變更紀錄與發布說明是否涵蓋不相容項目、必要操作及已知限制？
• 每份建置成品是否具有內容識別，並且能追溯來源提交與檢查結果？
• 如果同時存在多個版本，支援的程式、資料與互動契約組合是否已經確認？
• 部署紀錄是否能連回實際成品、設定版本與遷移工具？
• 前一個可用版本是否仍可取得，且復原限制已經驗證？

重點整理

• 專案需要分開管理原始碼提交、發布版本、建置成品與部署紀錄，再用穩定識別建立追溯鏈。
• 版本規則要表達相容性與變更條件，已公開的標籤及成品不得直接覆寫。
• 維護人員應該能從執行中的版本追溯到來源、檢查與遷移結果，也能確認哪些版本組合可以安全部署或復原。